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Foreword 



rd , 



This Technical Specification has been produced by the 3 Generation Partnership Project (3GPP). 

3GPP acknowledges the contribution of the Parlay X web services specifications from The Parlay Group. The Parlay 
Group is pleased to see 3GPP acknowledge and publish the present document, and the Parlay Group looks forward to 
working with the 3GPP community to improve future versions of the present document. 

The contents of the present document are subject to continuing work within the TSG and may change following formal 
TSG approval. Should the TSG modify the contents of the present document, it will be re-released by the TSG with an 
identifying change of release date and an increase in version number as follows: 

Version x.y.z 

where: 

X the first digit: 

1 presented to TSG for information; 

2 presented to TSG for approval; 

3 or greater indicates TSG approved document under change control. 

y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections, 
updates, etc. 

z the third digit is incremented when editorial only changes have been incorporated in the document. 



Introduction 



,rd , 



The present document is part 8 of a multi-part deliverable covering the 3 Generation Partnership Project; Technical 
Specification Group Core Network and Terminals; Open Service Access (OSA); Parlay X Web Services, as identified 
below: 



Part 1: 


"Common" 


Part 2: 


"Third party call" 


Part 3: 


"Call Notification" 


Part 4: 


"Short Messaging" 


Parts: 


"Multimedia Messaging" 


Part 6: 


"Payment" 


Part?: 


"Account management" 


Part 8: 


"Terminal Status" 


Part 9: 


"Terminal location" 


Part 10: 


"Call handling" 


Part 11: 


"Audio call" 


Part 12: 


"Multimedia conference" 


Part 13: 


"Address list management" 


Part 14: 


"Presence" 
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1 Scope 

The present document is Part 8 of the Stage 3 Parlay X Web Services specification for Open Service Access (OS A). 

The OS A specifications define an architecture that enables application developers to make use of network functionality 
through an open standardized interface, i.e. the OSA APIs. The concepts and the functional architecture for the OSA are 
contained in 3GPP TS 23.198 [3]. The requirements for OSA are contained in 3GPP TS 22.127 [2]. 

The present document specifies the Terminal Status Web Service aspects of the interface. All aspects of the Terminal 
Status Web Service are defined here, these being: 

Name spaces. 

Sequence diagrams. 

Data definitions. 

Interface specification plus detailed method descriptions. 

Fault definitions. 

Service policies. 

WSDL Description of the interfaces. 

The present document has been defined jointly between 3GPP TSG CT WG5, ETSI TISPAN and The Parlay Group. 

2 References 

The following documents contain provisions which, through reference in this text, constitute provisions of the present 
document. 

• References are either specific (identified by date of publication, edition number, version number, etc.) or 
non-specific. 

• For a specific reference, subsequent revisions do not apply. 

• For a non-specific reference, the latest version applies. In the case of a reference to a 3GPP document (including 
a GSM document), a non-specific reference implicitly refers to the latest version of that document in the same 
Release as the present document. 

[1] 3GPP TR 21.905: "Vocabulai-y for 3GPP Specifications". 

[2] 3GPP TS 22. 127: "Service Requirement for the Open Services Access (OSA); Stage 1 ". 

[3] 3GPP TS 23.198: "Open Service Access (OSA); Stage 2". 

[4] 3GPP TS 22.101: "Service aspects; Service principles". 

[5] W3C Recommendation (2 May 2001): "XML Schema Part 2: Datatypes". 

NOTE: Available at http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/ . 

[6] 3GPP TS 29.199-1: "Open Service Access (OSA); Parlay X web services; Part 1: Common". 

3 Definitions and abbreviations 
3.1 Definitions 

For the purposes of the present document, the terms and definitions given in 3GPP TS 29.199-1 [6] apply. 
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3.2 Abbreviations 

For the purposes of the present document, the abbreviations given in 3GPP TS 29.199-1 [6] apply. 

4 Detailed service description 

Terminal Status provides access to the status of a terminal through: 

• Request for the status of a terminal. 

• Request for the status of a group of terminals. 

• Notification of a change in the status of a terminal. 

The status of a terminal can be expressed as reachable, unreachable or busy - however not all terminals distinguish a 
busy status, so applications should be able to adapt to what information is available (using the service properties to 
determine available information). 

When a request for a group of terminals is made, the response may contain a full or partial set of results. This allows the 
service to provide results based on a number of criteria including number of terminals for which the request is made and 
amount of time required to retrieve the information. This allows the requester to initiate additional requests for those 
terminals for which information was not provided. 

5 Namespaces 

The data types are defined in the namespace: 

http://www.csapi.org/schema/parlayx/terminal_status/v2_2 
The TerminalStatus interface uses the namespace: 

http://www.csapi.org/wsdl/parlayx/terminal_status/v2_2 
The TerminalStatusNotificationManager interface uses the namespace: 

http://www.csapi.org/wsdl/parlayx/terminal_status/notification_manager/v2_2 
The TerminalStatusNotification interface uses the namespace: 

http://www.csapi.org/wsdl/parlayx/terminal_status/notification/v2_2 

The 'xsd' namespace is used in the present document to refer to the XML Schema data types defined in 
XML Schema [5]. The use of the name 'xsd' is not semantically significant. 
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Sequence diagrams 



6.1 Terminal status query 

Pattern: Request / Response. 

When an application is interested in determining the status of a terminal device, it may provide a terminal device 
address, and receive the status for the device requested. 



Application 



Terminai 
Status 



getStatus 



^ 



Retrieve terminal status 



9ve 



<- 



Status 
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6.2 Terminal status group query 



Pattern: Request / Response. 

When an application is interested in determining the status of a set of terminal devices, it may provide an array of 
terminal device addresses, including network managed group addresses, and receive the status for the set of devices 
requested. 



Application 



Terminal 
Status 



getStatusForGroup 



^ 



Process groups 

1 < 



Retrieve terminal status 



3ve 



Status list 



<- 
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6.3 Terminal status notification 

Pattern: Application Correlated Multiple Notification. 

An application can be notified of a change in the status of terminal devices. When the status of a terminal device 
changes, a notification message will be sent to the application. 



Application 



: Terminal Status 



Notification 



: Notification 
Application 



: Notification 
Web Service 



Create correlation id 



^ 



startNotification 



At some later time, an event occurs to 
trigger the notification 



statusNotification 



^ 



At some later time, the notification may t^ 
be cancelled 



endNotification 
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6.4 



Terminal Status Notification with Check Immediate 



In some applications, the terminal status notification will be used to watch for a specific status change. An example is a 
'call when available' service, where the terminal status is checked and determined to be not reachable or busy, and a 
notification is set up to notify the application when the terminal becomes reachable. Between the time that the original 
status determination and the time the notification is set up, the terminal status could change to reachable - thus the 
notification on change to reachable would not be sent. 

Using the check immediate flag, after the notification is established, the value of the terminal status wiU be determined, 
and if the criteria is matched then a notification will be sent immediately. The following sequence diagram shows this 
scenario. 



Application 



Terminal 
Status 



Terminal Status 
Notification 



: Notification 
Application 



getStatus 



: Notification 
Web Service 



i< 



Status 



Create correlation id 

1 < ^ 



startNotification with Qtieck Immediate = true 



Setlup notification 



«- 



Cfieck terminal status 



^- 



Apply count to notification 



<r- 



status Notification 



statusEnd 
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This sequence shows: 

• The Enterprise AppHcation checks the status of a terminal, and receives its status (in this scenario receiving 
Unreachable or Busy. 

• The Enterprise Application generates a correlator, and starts a notification with criteria defined to notify the 
Enterprise Web Service when the terminal state becomes Reachable and the check immediate flag set to true. 

• Sets up the notification to monitor terminal status changes. 

• Check the current status of the terminal, and determine if the status matches the criteria. 

• In this case, the criteria matches, and a notification is delivered to the Enterprise Web Service. 

• The count of notifications is incremented and compared to the notification count limit. 

• In this case, a single notification was requested, and the end notification message is sent. 

• The startNotification operation completes. 

This scenario includes the full set of interactions in one sequence, which also shows that the notifications can be 
received concurrent with the creation of the notification. 
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7 



XML Schema data type definition 



7.1 



Status enumeration 



List of possible status values. 



Enumeration 


Description 


Reachable 


Terminal is reachable 


Unreachable 


Terminal is not reachable 


Busy 


Terminal is busy 



7.2 



RetrievalStatus enumeration 



Enumeration of the status items that are related to an individual retrieval in a set. 



Enumeration 


Description 


Retrieved 


Status retrieved, with result in CurrentStatus element. 


NotRetrieved 


Status not retrieved, CurrentStatus is not provided (does not indicate an error, no attempt may have 
been made). 


Error 


Error retrieving status. 



7.3 



StatusData structure 



Data structure containing device identifier and its status. As this can be related to a query of a group of terminal devices, 
the ResultStatus element is used to indicate whether the information for the device was retrieved or not, or if an error 
occurred. 



Name 


Type 


Optional 


Description 


Address 


xsd:anyURI 


No 


Address of the Terminal Device to which the status information 
applies. 


ReportStatus 


RetrievalStatus 


No 


Status of retrieval for this address. 


CurrentStatus 


Status 


Yes 


Status of terminal. It is only provided if ReportStatus=Retrieved. 


Errorlnformation 


common:ServiceError 


Yes 


If ReportStatus is Error, this is the reason for the error. Error due 
to privacy verification will be expressed as POL0002 in the 
ServiceError. 



7.4 



Statuslnformation structure 



Name 


Type 


Optional 


Description 


Address 


xsd:anyURI 


No 


Address of the Terminal Device to which the status information applies. 


CurrentStatus 


Status 


No 


Status of terminal. 
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8 



Web service interface definition 



8.1 



Interface: TerminalStatus 



Request the status for a terminal or set of terminals. 

8.1 .1 Operation: GetStatus 

This operation is intended to retrieve the status for a single terminal. The URI provided is for a single terminal, not a 
group URI. If a group URI is provided, a PolicyException will be returned to the application. 



8.1.1.1 



Input message: GetStatusRequest 



Part name 


Part type 


Optional 


Description 


Address 


xsd:anyURI 


No 


Terminal to request status for 



8.1.1.2 



Output message: GetStatus Response 



Part name 


Part type 


Optional 


Description 


Result 


Status 


No 


Status for the terminal for which status was requested 



8.1.1.3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• SVCOOOl: Service error. 

• SVC0002: Invahd input value. 
PohcyException from 3GPP TS 29.199-1 [6]: 

• POLOOOl: Policy error. 

• POL0002: Privacy error. 

• POL0006: Groups not allowed. 

8.1.2 Operation: GetStatusForGroup 

The getStatusForGroup operation initiates a retrieval activity, where one or more terminals, or groups of terminals, may 
have their status determined. 

The Web Service may return a result set that does not include complete information, allowing the Web Service 
implementation to choose to deliver a partial set of results to accommodate other conditions, such as avoiding timeouts. 
In this case, the addresses for which no attempt was made to provide data will be marked NotRetrieved in the result for 
each address this applies to. 



8.1.2.1 



Input message: GetStatusForGroup Request 



Part name 


Part type 


Optional 


Description 


Addresses 


xsd:anyURI [1.. unbounded] 


No 


List of URIs to get status for, including group URIs 
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8.1 .2.2 Output message: GetStatusForGroupResponse 



Part name 


Part type 


Optional 


Description 


Result 


StatusData [1 ..unbounded] 


No 


Set of results for the request 



8.1.2.3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• SVCOOOl: Service error. 

• SVC0002: Invalid input value. 

• SVC0004: No valid addresses. 

• SVC0006: Invalid group. 
PolicyException from 3GPP TS 29.199-1 [6]: 

• POLOOOl: Policy error. 

• POL0003: Too many addresses. 

• POL0006: Groups not allowed. 

• POL0007: Nested groups not allowed. 

8.2 Interface: TerminalStatusNotificationManager 

Set up notifications for terminal status changes. 

8.2.1 Operation: StartNotification 

Notifications of status changes are made available to applications. The number and duration of notifications may be 
requested as part of the setup of the notification or may be governed by service policies, or a combination of the two. 

If Checklmmediate is set to true, then the notification will be set up, and then the current value of the terminal status 
will be checked. If the terminal status meets the criteria provided, a notification will be sent to the application. This 
notification will count against the count requested. This addresses the case where the status of the device changes 
during the time the notification is being set up, which may be appropriate in some applications. 

The correlator provided in the reference must be unique for this Web Service at the time the notification is initiated, 
otherwise a ServiceException (SVC0005) will be returned to the application. 

If the frequency requested is more often than allowed by the service policy, then the value in the service policy will be 
used. If the duration requested exceeds the time allowed in the service policy, then the value in the service policy will 
be used. If the notification period (duration) ends before all of the notifications (count) have been delivered, then the 
notification terminates. In all cases, when the notifications have run their course (by duration or count), an end of 
notifications message will be provided to the application. 

Service policies may govern what count values can be requested, including maximum number of notifications allowed 
and whether unlimited notifications can be requested (i.e. either by not specifying the optional Count message part or by 
specifying it with a value of zero). If the count value requested is not in policy, a PolicyException (POL0004 or 
POL0005 as appropriate) will be returned. 
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8.2.1.1 



Input message: StartNotification Request 



Part name 


Part type 


Optional 


Description 


Reference 


common:SimpleReference 


No 


Notification endpoint definition 


Addresses 


xsd:anyURI 
[1.. unbounded] 


No 


Addresses of terminals to nnonitor 


Criteria 


Status [1.. unbounded] 


No 


List of status values to generate notifications for (these 
apply to all addresses specified) 


Checl<lmmediate 


xsd:boolean 


No 


Check status immediately after establishing notification 


Frequency 


commoniTimelVletric 


No 


Maximum frequency of notifications (can also be 
considered minimum time between notifications) 


Duration 


commoniTimelVletric 


Yes 


Length of time notifications occur for, do not specify to use 
default notification time defined by service policy 


Count 


xsd:integer 


Yes 


IVIaximum number of notifications. For no maximum, either 
do not specify this part or specify a value of zero. 



8.2.1.2 



Output message: StartNotificationResponse 



Part name 


Part type 


Optional 


Description 


None 









8.2.1.3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• SVCOOOl: Service error. 

• SVC0002: Invalid input value. 

• SVC0004: No valid addresses. 

• SVC0005: Duplicate correlator. 

• SVC0006: Invalid group. 
PolicyException from 3GPP TS 29.199-1 [6]: 

• POLOOOl: Policy error. 

• POL0003: Too many addresses. 

• POL0004: Unlimited notifications not supported. 

• POL0005: Too many notifications requested. 

• POL0006: Groups not allowed. 

• POL0007: Nested groups not allowed. 

• POL0009: Invalid frequency requested. 

• POL0200: Busy criteria not supported. 

8.2.2 Operation: EndNotification 

The application may end a notification using this operation. Until this operation returns, notifications may continue to 
be received by the application. 

An end of notification (statusEnd) message will not be delivered to the application for a notification ended using this 
operation. 
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8.2.2.1 



Input message: EndNotificationRequest 



Part name 


Part type 


Optional 


Description 


Correlator 


xsd:string 


No 


Correlator of request to end 



8.2.2.2 Output message: EndNotification Response 



Part name 


Part type 


Optional 


Description 


None 









8.2.2.3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• S VCOOO 1 : Service error. 

• SVC0002: Invalid input value. 
PolicyException from 3GPP TS 29.199-1 [6]: 

• POLOOOl: Policy error. 



8.3 



Interface: TerminalNotification 



Notification interface to which notifications are delivered. 

8.3.1 Operation: StatusNotification 

When the status of monitored devices change, a notification is delivered to the application with the new status 
information for each of the devices. If a group identifier was used, the terminal device URl is provided, not the group 
URL 



8.3.1.1 



Input message: StatusNotification Request 



Part name 


Part type 


Optional 


Description 


Correlator 


xsd:strlng 


No 


Correlator provided in request to set up this notification 


TerminalStatus 


Statuslnformation 
[1.. unbounded] 


No 


List of Statuslnformation elements describing address and 
new terminal status. 



8.3.1.2 



Output message: StatusNotification Response 



Part name 


Part type 


Optional 


Description 


None 









8.3.1.3 

None. 



Referenced faults 



8.3.2 Operation: StatusError 



The status changed error message is sent to the application to indicate that the notification is being cancelled by the 
Web Service. 
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8.3.2.1 



Input message: StatusErrorRequest 



Part 
name 


Part type 


Optional 


Description 


Correlator 


xsd:string 


No 


Correlator provided in request to set up this notification. 


Address 


xsd:anyURI 


Yes 


Address of terminal if the error applies to an individual terminal, or not 
specified if it applies to the whole notification. 


Reason 


common:ServiceError 


No 


Reason notification is being discontinued. 



8.3.2.2 



Output message: StatusErrorResponse 



Part name 


Part type 


Optional 


Description 


None 









8.3.2.3 

None. 



Referenced faults 



8.3.3 Operation: StatusEnd 



The notifications have completed for this correlator. This message will be delivered when the duration or count for 
notifications have been completed. This message will not be delivered in the case of an error ending the notifications or 
deliberate ending of the notifications (using endNotification operation). 



8.3.3.1 



8.3.3.2 



Input message: StatusEnd Request 



Part name 


Part type 


Optional 


Description 


Correlator 


xsd:string 


No 


Correlator provided in request to set up this notification. 



Output message: StatusEndResponse 



Part name 


Part type 


Optional 


Description 


None 









8.3.3.3 

None. 



Referenced faults 



Fault definitions 



New fault definitions for this service. 



9.1 Fault: PolicyException 

Busy criteria not supported. 



Name 


Description 


IVIessage Id 


<POL0200> 


Text 


Busy criteria is not supported. 


Variables 


None. 
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1 Service po icies 


Name 


Type 


Description 


BusyAvailable 


xsd:boolean 


Can busy be returned as a status or be a trigger 


MaximumNotificationAddresses 


xsd:int 


IVIaximum number of addresses for which a notification can be 
set up 


MaximumNotificationFrequency 


common:TimeMetric 


IVIaximum rate of notification delivery (also can be considered 
minimum time between notifications) 


MaximumNotification Duration 


common ;TimeMetric 


Maximum amount of time a notification may be set up for 


MaximumCount 


xsd:int 


IVIaximum number of notifications that may be requested 


UnlimitedCountAllowed 


xsd:boolean 


Allowed to specify unlimited notification count (i.e. either by not 
specifying the optional Count message part in 
StartNotificationRequest or by specifying a value of zero) 


GroupSupport 


xsd:boolean 


Groups may be included with addresses 


NestedGroupSupport 


xsd:boolean 


Are nested groups supported in group definitions 



£75/ 



3GPP TS 29.1 99-08 version 6.4.0 Release 6 20 ETSI TS 1 29 1 99-8 V6.4.0 (2007-03) 



Annex A (normative): 
WSDL for Terminal Status 



The document/literal WSDL representation of this interface specification is compliant to 3GPP TS 29.199-1 [6] and is 
contained in text files (contained in archive 29199-08-640-doclit.zip) which accompanies the present document. 
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Annex B (informative): 

Description of Parlay X Web Services Part 8: Terminal 

Status for 3GPP2 cdma2000 networks 

This annex is intended to define the OSA Parlay X Web Services Stage 3 interface definitions and it provides the 
complete OSA specifications. It is an extension of OSA Parlay X Web Services specifications capabilities to enable 
operation in cdma2000 systems environment. They are in alignment with 3GPP2 Stage 1 requirements and Stage 2 
architecture defined in: 

[1] 3GPP2 X.SOOll-D: 'cdma2000 Wireless IP Network Standard ", Version 1.1 

[2] 3GPP2 S.R0037-0: "IP Network Architecture Model for cdma2000 Spread Spectrum Systems", 

Version 3.0 

[3] 3GPP2 X.S0013-A: "All-IP Core Network Multimedia Domain" 

These requirements are expressed as additions to and/or exclusions from the 3GPP Release 6 specification. 

The information given here is to be used by developers in 3GPP2 cdma2000 network architecture to interpret the 3GPP 

OSA specifications. 



B.1 General Exceptions 



The terms 3GPP and UMTS are not applicable for the cdma2000 family of standards. Nevertheless these terms are used 
(3GPP TR 21.905) mostly in the broader sense of "3G Wireless System". If not stated otherwise there are no additions 
or exclusions required. 

CAMEL mappings are not applicable for cdma2000 systems. 



B.2 Specific Exceptions 
B.2.1 Clause 1: Scope 

There are no additions or exclusions. 

B.2.2 Clause 2: References 

There are no additions or exclusions. 

B.2. 3 Clause 3: Definitions and abbreviations 

There are no additions or exclusions. 

B.2. 4 Clause 4: Detailed service description 

There are no additions or exclusions. 

B.2. 5 Clause 5: Namespaces 

There are no additions or exclusions. 
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B.2.6 Clause 6: Sequence diagrams 

There are no additions or exclusions. 

B.2.7 Clause 7: XML Schema data type definition 

There are no additions or exclusions. 

B.2.8 Clause 8: Web Service interface definition 

There are no additions or exclusions. 

B.2.9 Clause 9: Fault definitions 

There are no additions or exclusions. 

B.2.10 Clause 10: Service policies 

There are no additions or exclusions. 

B.2.1 1 Annex A (normative): WSDL for Terminal Status 

There are no additions or exclusions. 
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Annex C (informative): 
Change history 



Change history 


Date 


TSGff 


TSG Doc. 


CR 


Rev 


Subject/Comment 


Cat 


Old 


New 


Dec 2003 


CN 21 


NP-030552 


-- 


-- 


Submitted to CN#22 for Information 


-- 


1.0.0 


-- 


Jan 2004 










Added Tine W3C WSDL representation of ttie APIs specified in the 
present document is contained in a set of files which accompany the 
present document: 

px0326rpcenc.zip 

px0326rpclit.zip 




1.0.1 




Jun 2004 


CN_24 


NP-040274 


- 


- 


Split into multi-part specification. 29.199-On, for n=1 ,2... 9. 
Submitted to CN#24 for Information 


- 


1.0.3 


- 


Sep 2004 


CN 25 


NP-040360 


-- 


-- 


Draft v200 submitted to TSG CN#25 for Approval. 


-- 


2.0.0 


6.0.0 


Jun 2005 


CT 28 


CP-050221 


0001 


-- 


Optionals for Part 8 


F 


6.0.0 


6.1.0 


Dec 2005 


CT 30 


CP-050573 


0002 


-- 


Make the CurrentStatus element an optional parameter 


F 


6.1.0 


6.2.0 


Dec 2005 


CT 30 


CP-050573 


0003 


-- 


Allow list of addresses in StatusNotificationRequest 


F 


6.1.0 


6.2.0 


Jun 2006 


CT 32 


CP-060195 


0004 


-- 


Change reference to OSA Stage 2 from 23.127 to 23.198 


F 


6.2.0 


6.3.0 


Mar 2007 


CT 35 


CP-070045 


0005 


-- 


Add OSA Parlay Web Services support for 3GPP2 networks 


F 


6.3.0 


6.4.0 
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